<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Candidate Steps</title>
</head>

<body>

<h2>Candidate Steps</h2>

<p>JBehave uses method annotations in Java classes to associate an
executable Java method to a <a
	href="javadoc/core/org/jbehave/core/steps/StepCandidate.html">StepCandidate</a>.
Each step candidate corresponds to one Java method and to one <a
	href="javadoc/core/org/jbehave/core/steps/StepType.html">StepType</a>.
A step candidate holds the regex pattern contained in the annotation
value, which is used to do the matching with the textual steps in the
scenarios.</p>

<p>Let's look at a concrete example:</p>
<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class TraderSteps { // Look, Ma', I'm just a POJO

    private Stock stock;

    @Given("a stock of symbol $symbol and a threshold of $threshold")
    public void aStock(String symbol, double threshold) {
        stock = new Stock(symbol, threshold);
    }

    @When("the stock is traded at $price")
    @Alias("the stock is sold at $price")
    public void theStockIsTradedAt(double price) {
        stock.tradeAt(price);
    }

    @Then("the alert status should be $status")
    public void theAlertStatusShouldBe(String status) {
        ensureThat(stock.getStatus().name(), equalTo(status));
    }

}
]]>
</script>

<p>For each method annotated with one of the <a
	href="annotations.html">step annotations</a>, a step candidate is
created. Note that each method can supports <a href="aliases.html">aliases</a>
and a different step candidate is created for each alias.</p>

<p>So, given one or more steps class instances, each containing one
or more annotated methods, JBehave collects a list of step candidates,
which are then used to match the textual steps found in the scenarios
being run. For each given <a
	href="javadoc/core/org/jbehave/core/steps/StepType.html">StepType</a>,
<b>the regex pattern must be unique</b>.</p>

<p>Hence, the following two methods are allowed to have the same
regex pattern, because they correspond to different step types:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @Given("the stock is traded at $price")
    public void theStockWithPrice(double price) {
        // ...
    }

    @When("the stock is traded at $price")
    public void theStockIsTradedAt(double price) {
        // ...
    }
]]>
</script>

<p>By contrast, the following would result in a runtime failure when
running the scenario:</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
    @When("the stock is traded at $price")
    public void theStockWithPrice(double price) {
        // ...
    }

    @When("the stock is traded at $price")
    public void theStockIsTradedAt(double price) {
        // ...
    }
]]>
</script>

<p>Note that in the example above <b>TraderSteps</b> is a POJO, i.e.
it does not need to extend any JBehave class. JBehave provides the 
<a
	href="javadoc/core/org/jbehave/core/steps/InjectableStepsFactory.html">InjectableStepsFactory</a>
as a factory to create from these POJO steps instances the <a
	href="javadoc/core/org/jbehave/core/steps/CandidateSteps.html">CandidateSteps</a>
it needs to extract the step candidates. The <a
	href="javadoc/core/org/jbehave/core/steps/InstanceStepsFactory.html">InstanceStepsFactory</a>
takes each steps instance provided by the user and wraps it in a <a
	href="javadoc/core/org/jbehave/core/steps/Steps.html">Steps</a>
instance, which is the default implementation of <b>CandidateSteps</b>:
</p>

<script type="syntaxhighlighter" class="brush: java">
<![CDATA[
public class TraderStory extends JUnitStory {

    @Override
    public InjectableStepsFactory stepsFactory() {
        return new InstanceStepsFactory(configuration(), new TraderSteps(new TradingService()), new AndSteps(),
                new CalendarSteps(), new PriorityMatchingSteps(), new SandpitSteps(), new SearchSteps(),
                new BeforeAfterSteps());
    }
}
]]>
</script>

<span class="followup">It is strongly recommended to define your
steps instances as POJOs and to not extend the Steps class directly. This
allow you not to have any tie-ins with the Steps class implementation
(which may be subject to change) and also to use <a
	href="dependency-injection.html">dependency injection</a> to compose
your steps instances using your preferred container.</span>

<div class="clear">
<hr />
</div>

</body>
</html>
